HPAVC/HPAVC CD-ROM.iso/3DVIS10.ZIP/3DVISION.DOC

Text File | 1996-02-29 | 17KB | 413 lines

        _____     _       _     _                  _
       |___ /  __| |_   _(_)___(_) ___  _ __    __| | ___   ___
         |_ \ / _` \ \ / / / __| |/ _ \| '_ \  / _` |/ _ \ / __|
        ___) | (_| |\ V /| \__ \ | (_) | | | || (_| | (_) | (__
       |____/ \__,_| \_/ |_|___/_|\___/|_| |_(_)__,_|\___/ \___|


------------
INTRODUCTION
------------

    3DVISION is a set of programs that display 3-dimensional objects and allow
you to make real-time rotations with them. It  works  on  IBM AT  compatibles,
with EGA or VGA videos.

    3DVISION was inspired on  the  3DV.EXE  program, written  by  Oscar García
from New Zealand. 3DVISION  has  some  capabilities  that  3DV  doesn't  have,
as  the  ramdom  displaying  of objects on screen, and the changing of colors.
However, the  original  3DV.EXE  runs at a  faster  rate and has a better user
interface. The  3DVISION and 3DV data files are 100% compatible. You  can  get
the 3DV  program  at  the  SimTel's  msdos/graphics  subdirectory or from many
others sites with names that look like 3DV25.ZIP or 3DKIT1.ZIP.

    The package  3DVISION contains the executables  3DVISION.EXE, 3DVRAND.EXE,
3DVSURF.EXE,  3DVCOLOR.COM, RNDCOLOR.COM and  about  40  data files containing
3D objects, all  of  them  constructed  on  mathematical parametric curves and
surfaces equations. See the end of each *.3DV data file to get  the  equations
used (this can be made writting C:\> COMMENT file_name[.3dv]).

    All the programs  were written and compiled with  the  old  Turbo  C  2.0.
I  did  purchased the Borland C++ 4.0 license on december/1994, but I am still
without courage to learn how it works.

    Press the ESC  key to quit any of the programs. When the mouse is enabled,
press  any  buttom to quit.  All of  the  programs will use the extension .3DV
as default, that is, you don't need to append it.


------------
3DVISION.EXE
------------

    The main program is  3DVISION.EXE. It displays the objects saved in  *.3DV
files. It can works with the keyboard or with  the  mouse.  You  can alternate
the  usage between keyboard/mouse only using the configuration files  (see the
item CONFIGURATION below).
    Data files are given as parameters at the DOS command line:

         C:\>  3DVISION Data_File [Config_File]
where
    Data_file is a text file with the scene description in 3DV format
and
    Config_File is an optional parameter with the configuration file name

    After the displaying, press one of the following keys:

      Right, left arrows:         Rotate around the z axis
      Up, down arrows:            Rotate around the y axis
      Ctrl-up, Ctrl-down arrows:  Rotate around the x axis
      PgDn, PgUp:                 Zoom in/out
      F1:                         Change ramdomly the colors
      F2:                         Save the new colors (on files whose
                       extensions are .1, .2, .3, ...)
      ESC:                        Quit

    Type 3DVISION ?,  3DVISION /?  or  3DVISION /h  at the DOS prompt to get a
brief help screen.

Example: To display a file named CURVE1.3DV using the default configuration or
the standard configuration file 3DVISION.CFG, just type
             C:\> 3DVISION curve1
    To display  the same file  using the  configuration file  CONFIG.CFG, type
             C:\> 3DVISION curve1 config


-----------
3DVRAND.EXE
-----------

    3DVRAND displays a selected object on screen rotating it randomly.  During
the execution, press any key to freeze the image. Then, press another  key  to
continue the ramdom rotations.
    The usage is the same as 3DVISION.EXE:

           C:\> 3DVRAND Data_File [Config_File]

     To get a help screen, type  3DVRAND ?  or  3DVRAND /h  at the DOS prompt.


-----------
3DVSURF.EXE
-----------

    3DVSURF creates a 3DV file with points of a given  surface  in  parametric
form F(x, y) = (f1(x, y), f2(x, y), f3(x, y)). You can give the optional names
of the variables  as  parameters (default = "x" and "y").  Hidden  curves  are
displayed.

    The usage is: 3DVSURF file_name[.3DV] [variable_1] [variable_2]

    Using this parametric form, functions z = G(x, y) can be given as
               f1(x, y) = x
               f2(x, y) = y
               f3(x, y) = G(x, y)

    The  valid  operations are + (addition),  - (subtraction),  * (multiplica-
tion),  / (division)  and  ^ (power).
    The valid functions  are the  trigonometric  SIN,  COS,  TG;  the  inverse
trigonometric ARCSIN, ARCCOS, ARCTG; the natural logarithm LN; the exponential
EXP; the hyperbolic  SINH,  COSH, TGH;  the  approximations  to integers  INT,
ROUND;  the  square  root SQRT; the square SQR; the absolute value ABS and the
SIGN function.
    Examples of valid expressions are:  3*sin(x)*cos(y),  (1 + (1 - x^2)/5)^2,
(1 - u*cos(u))*sin(2*v)/3   and  sqrt(abs(0.5 + round(u + v))).
    You  have to give  the  [minimum, maximum] values of the variables and the
number of subdivisions of these intervals.

Example: Write at the DOS prompt
               C:\> 3DVSURF  graph  u  v
to create  a  file  named  GRAPH.3DV  with  the  points of the graphics of the
surface  F(u, v) = (f1(u, v), f2(u, v), f3(u, v)),  where  f1, f2, f3  will be
asked later.


------------
3DVCOLOR.COM
------------

    3DVCOLOR is a simple  utility to change the colors of 3DV files. The  file
names must be given as two parameters. The usage is:

       C:\> 3DVCOLOR  Source_file[.3DV]  Destination_file[.3DV]

where
    Source_file is the file that originally contains the objects
 and
    Destination_file will be created by 3DVCOLOR and contains the same
                         objects with new selected colors.

    The contents of the source_file remain unchanged.

    You  can  select  the  colors using the rigth and left arrows and pressing
the ENTER key.

Example:  To  create  a  file  named  FILE2.3DV  with  different  colors  from
another file FILE1.3DV previously saved on disk, write
            C:\> 3DVCOLOR file1 file2
    Then, you will be asked which colors you want to change.


------------
RNDCOLOR.COM
------------

    RNDCOLOR  changes  ramdomly the  colors on a .3DV file. Its  usage  is the
same as 3DVCOLOR - just give the name of the files as parameters:

        C:\> RNDCOLOR  original_3DV_file  new_3DV_file

Example: Using  the file  OLDLINES.3DV as source, RNDCOLOR  creates a new file
called NEWLINES.3DV with the same scene, but with randomly changed colors:
        C:\> RNDCOLOR  OldLines.3dv  NewLines.3dv


-------------
CONFIGURATION
-------------

    You  can  define  one  or  various  configuration  files to  3DVISION  and
3DVRAND.  The  standard  configuration  file is 3DVISION.CFG. The default file
extension is .CFG.
    When 3DVISION or 3DVRAND begin running, the first thing they do is to look
for a file named  3DVISION.CFG.  If  they  find  this file, they interpret its
lines one by  one. Later,  these  programs  verify  whether  there is a second
configuration file name, given as a second parameter. If there is such  second
file, it will be opened and executed. For example, if you  write  at  the  DOS
prompt

           C:\> 3DVISION  house.3dv  config2.cfg

then, 3DVISION will display HOUSE.3DV  using  the  configuration  of the files
3DVISION.CFG (the standard) and CONFIG2.CFG. The commands in CONFIG2.CFG  will
overwrite those of 3DVISION.CFG.  The  configuration  files don't need to have
the same commands - they can compensate each other.
    To  create  a configuration  file,  use  any  text  editor.  Even the COPY
command of DOS can be used  (write  COPY CON Config_File_Name  and press F6 at
the end). Beware  of  special  characters that some text editors append to the
files.
    Comments can be added, written after a semicolon.
    Some options of 3DVISION or 3DVRAND can be changed only using a configura-
tion file.  The  mouse/keyboard  usage  and  the  method of projection are two
examples of options that cannot be changed after  the  beginning of execution.
   The  configuration file can have the following commands.  N  is  a  natural
number. No matter if are used upper or lower case letters.

Command            What it does
----------------   -----------------------------------------------------------
mouse = 1 or 0     Enables  (mouse = 1)  or  disables  the  mouse  usage.  The
           default is mouse = 0.

size = N           Size of the objects.  If size <= 170, then the objects will
           not be clipped. The default is size = 170.

method = 1 or 0    Defines the method  of  projection  of  the  3D objects. If
           method = 0 (default), parallel (orthogonal) projection will
           be  used. If  method = 1,  a perspective projection will be
           used.

file = File_Name   File name in 3DV format to be displayed.

bottom = 1 or 0    Displays or not a status  line at the lower part of screen.
           The status line contains the file name being used  and  the
           variation of the rotation angles. The default is bottom =1.

theta = N          Rotation around the z  axis  increment  (in  degrees).  The
           default is theta = 1°.

phi = N            Rotation around the  y  axis  increment  (in degrees).  The
           default is phi = 1°.

sigma = N          Rotation around  the  x  axis increment  (in degrees).  The
           default is sigma = 1°.

delay = N          Pause (in milliseconds)  between  two  images. Used only by
           3DVRAND. The default is delay = 50.

sensibility = N    Mouse sensibility. The default is sensibility = 50.

proj = N           The norm of orthogonal  vectors  that  are the basis of the
           mouse movement plane. The default is proj = 1.

lim1 = N           Maximum random number of multiples of increments of  theta.
           Used only by 3DVRAND. The default is lim1 = 10.

lim2 = N           Maximum random number of  multiples of increments  of  phi.
           Used only by 3DVRAND. The default is lim2 = 10.

lim3 = N           Maximum random number of  multiples of increments of sigma.
           Used only by 3DVRAND. The default is lim3 = 10.


--------------
THE 3DV FORMAT
--------------

    A  3DV data file  is a text (ASCII) file  that contains  a list of points,
followed by a list of moving or drawing instructions.  It  has  the  following
structure:

       N                    Total number of points to be drawn
       x1  y1  z1           1st. point
       x2  y2  z2           2nd. point
       ...                  ...
       xN  yN  zN           The last point
       M                    Total number of movements or drawings
       p1  c1               1st. movement or drawing
       p2  c2               2nd. movement or drawing
       ...                  ...
       pM  cM               The last movement or drawing

where

■ (xi, yi, zi) are the coordinates of the i-th point in 3D space

■ (p1, p2, ..., pM) is a sequence  of  integers  greater  than or equal to  1.
  It defines the order in which the points will be drawn or the one  which  it
  will be moved to. The first point to be actually drawn  or moved  to  is the
  p1-th point, the second is the p2-th point and so on.

■ (c1, c2, ..., cM)  are  their  respective  colors.  They  are integers  from
  0  to  15  (1 = blue, 2 = green, 3 = cyan, ..., 15 = white).

■ If  ci = 0  then it means a movement to the pi-th point. If ci is not  0, it
  means a color number and that you have to draw a line from the current point
  to the pi-th point using the color ci.

Example: A yellow (color = 14) cube with vertices  (-1, -1, -1),  (-1, 1, -1),
(1, 1, -1),  (1, -1, -1),  (-1, -1, 1),  (-1, 1, 1), (1, 1, 1), (1, -1, 1) can
be described in 3DV format as

               8
              -1   -1   -1
              -1    1   -1
               1    1   -1
               1   -1   -1
              -1   -1    1
              -1    1    1
               1    1    1
               1   -1    1
               16
               1    0
               2   14
               3   14
               4   14
               1   14
               5   14
               6   14
               7   14
               8   14
               5   14
               2    0
               6   14
               3    0
               7   14
               4    0
               8   14


--------------------------
PROJECTIVE TRANSFORMATIONS
--------------------------

    Projections of  points in 3D space to a plane constitute  a  simple  topic
that some books and some persons use to complicate.
    The projections can be classified in parallel  or  in  perspective.  In  a
parallel projection, the objects are not deformed because the  projection rays
are parallel. In the perspective type, the projection rays  are  not  parallel
and you can see vanishing points.
    The simplest parallel projections are the 'orthographic' ones. They simply
annul the information in one coordinate, e.g. as  T(x, y, z) = (0, y, z).
    You can get good results with  the  'axonometric'  projections.  They  are
rotations followed by an orthographic projection. An example of an axonometric
projection (in matrix form) is:

               ┌  cos Θ   sin Θ  0 ┐┌  cos φ  0   sin φ ┐┌ 0  0  0 ┐
   T(x,y,z) = [ x y z ]│ -sin Θ   cos Θ  0 ││    0    1     0   ││ 0  1  0 │
               └   0        0    1 ┘└ -sin φ  0   cos φ ┘└ 0  0  1 ┘

that is,  T(x, y, z)  =  (0, x sin Θ + y cos φ,
                      x cos Θ sin φ - y sin Θ sin φ + z cos φ)

    Thus, if you want to plot the point (x, y, z) in  3D  space, just plot the
point  ( x sin Θ + y cos φ,  x cos Θ sin φ - y sin Θ sin φ + z cos φ)  on  the
yOz plane.  Here, Θ and φ are the rotation angles (in radians) about the z and
y axis.
    If you want to rotate σ radians around the x axis too, just add the matrix

               ┌  1      0       0    ┐
               │  0    cos σ   sin σ  │
               └  0   -sin σ   cos σ  ┘

as the fourth factor on the matrix product above.

    Thereby, you can use the following steps to plot a point (x, y, z):

    (1) Get the values of (x, y, z), reading them on the file.

    (2) Project (x, y, z)   on  a   plane,   using  an   axonometric   (or   a
    perspective) projection.  This  can be made by calling  the   function
    ProjectPoint(x, y, z, &X, &Y). The C source to ProjectPoint() can  be:

    void ProjectPoint(float x, float y, float z,
                       int *X_proj, int *Y_proj) {
      float Y, Z;
      Y = x*sin(theta) + y*cos(theta);
      Z = (x*cos(theta) - y*sin(theta))*sin(phi) + z*cos(phi);
      *X_proj = (int) (A + Size*Y);
      *Y_proj = (int) (B - Size*Z);
    }

    where
    ■ A, B, theta, phi and Size are global variables.
    ■ (A, B) are screen coordinates chosen as the origin of the  cartesian
      system.
    ■ theta and phi are the rotation  angles  around the  z  and  y  axis.

    (3) Draw the (X, Y) point on screen: putpixel(X, Y, color).

    There are  too  many  books  about projections. I would like to refer only
two, both from the McGraw-Hill catalogue:

          "Theory and problems of Computer Graphics"
           (Schaum's Outline Series)
           R. Plastock, G. Kalley
 and
          "Mathematical Elements for Computer Graphics"
           D. Rogers, J. Adams


-----------
FINAL WORDS
-----------

     These  programs may not be sold or included in another software. However,
the  complete  3DVIS10.ZIP  file may be copied and widely distributed, keeping
the original files and credits immutable.

     These programs were tested a large number of times and it is my hope that
they  will  work  properly.  The  author  of  these  simple  programs  is  not
responsible for any damage supposedly caused for their misusage. Use  them  by
your own  risk.  You  wouldn't expect me to say something here different  from
this, would you?

     Comments  and  suggestions  are  welcome  and  will  be  appreciated.  My
eletronic   mail  is   [e-mail]   or  [e-mail]
(note  that  the  character  0 is zero).  Like  many  things here  in  Brazil,
it doesn't work as it should do. So, sometimes I don't receive  messages  sent
to me. Under normal conditions, I always reply ALL the messages that reach me.

    My thanks to professor Antônio Sales da Silva who made precious hints  and
some corrections to the text in English.

    3DVISION  is  freeware, completely free of charges. But, if you  like  it,
I would be very pleased to receive a postcard from your city.

┌────────────────────────────────────────────────────────────────────────────┐
│  Lenimar Nunes de Andrade                                                  │
│  Rua Lindolfo Chaves, 381                                                  │
│  58051-200 Joao Pessoa, PB - BRAZIL                                        │
│                                                                            │
│  *** At the most easterly place in our poor and beloved South America ***  │
└────────────────────────────────────────────────────────────────────────────┘